<table width="100%"><tr><td width="20%">
<a href="../index.html">&lt; index</a><br />
<a href="index.html">&lt; 5. Image toolkit</a>
</td><td width="60%">
<p align="center">
=====================================<br />
5.10 Blitting an image on a console<br />
=====================================<br />
</p></td><td width="20%">
</td></tr></table>
<style type="text/css">
.code { color:#444444; background-color:#EEEEEE;}
pre { color:#444444; background-color:#EEEEEE;}
table.param td { border : 1px solid #000000; }
th { background-color: #44BBFF; color: #FFFFFF }
table.none td { border : 0 }
</style>
<h3>TCODImage::blit</h3>
You can draw an image on a console (by changing the cells background color) :<br/>
The first function allows you to specify the floating point coordinates of the center<br />
of the image, and its scale and rotation angle.<br />
The image will be rendered with sub-cell accuracy (no to be confused with sub-cell resolution, which is not yet implemented and should appear only with libtcod 1.5). For example, if you increase x by 0.01 per frame,<br/>
you will achieve a smooth scrolling effect.<br />
<p class="code"><pre>
C++ : void TCODImage::blit(TCODConsole *console, float x, float y, TCOD_bkgnd_flag_t bkgnd_flag = TCOD_BKGND_SET, float scalex=1.0f, float scaley=1.0f, float angle=0.0f) const
C   : void TCOD_image_blit(TCOD_image_t image, TCOD_console_t console, int x, int y, TCOD_bkgnd_flag_t bkgnd_flag, float scalex, float scaley, float angle)
Py  : image_blit(image, console, x, y, bkgnd_flag, scalex, scaley, angle)
</pre></p>
<table class="param">
<tr><th>Parameter</th><th>Description</th></tr>
<tr><td>image</td><td>In the C version, the image handler, obtained with the <a href="image_load.html">load</a> function.</td></tr>
<tr><td>console</td><td>The console on which the image will be drawn. In the C version, use NULL for the root console.</td></tr>
<tr><td>x,y</td><td>Coordinates in the console of the center of the image.</td></tr>
<tr><td>flag</td><td>This flag defines how the cell's background color is modified. See <a href="../console/bkgnd_flag.html">TCOD_bkgnd_flag_t</a>.</td></tr>
<tr><td>scale</td><td>Scale coefficient. Must be &gt; 0.0.</td></tr>
<tr><td>angle</td><td>Rotation angle in radians.</td></tr>
</table>
Example :<br />
<p class="code"><pre>
C++ : TCODImage *pix = TCODImage("mypix.bmp");
      pix->blit(TCODConsole::root,40.0f,25.0f);
C   : TCOD_image_t pix = TCOD_image_new(80,50);
      TCOD_image_blit(pix,NULL,40,25,TCOD_BKGND_SET,1.0f,1.0f,0.0f);
Py  : pix = libtcod.image_new(80,50)
      libtcod.image_blit(pix,0,40,25,libtcod.BKGND_SET,1.0,1.0,0.0)
</pre></p>

<h3>TCODImage::blitRect</h3>
The second function allows you to easily map an image to a specific part of a console, by<br />
specifying a rectangular part of the console (upper-left corner and size).
<p class="code"><pre>
C++ : void TCODImage::blitRect(TCODConsole *console, int x, int y, int w=-1, int h=-1, TCOD_bkgnd_flag_t bkgnd_flag = TCOD_BKGND_SET ) const
C   : void TCOD_image_blit_rect(TCOD_image_t image, TCOD_console_t console, int x, int y, int w, int h, TCOD_bkgnd_flag_t bkgnd_flag)
Py  : image_blit_rect(image, console, x, y, w, h, bkgnd_flag)
</pre></p>
<table class="param">
<tr><th>Parameter</th><th>Description</th></tr>
<tr><td>image</td><td>In the C version, the image handler, obtained with the <a href="image_load.html">load</a> function.</td></tr>
<tr><td>console</td><td>The console on which the image will be drawn. In the C version, use NULL for the root console.</td></tr>
<tr><td>x,y</td><td>Coordinates in the console of the upper-left corner of the image.</td></tr>
<tr><td>w,h</td><td>Dimension of the image on the console. Use -1,-1 to use the image size.</td></tr>
<tr><td>flag</td><td>This flag defines how the cell's background color is modified. See <a href="../console/bkgnd_flag.html">TCOD_bkgnd_flag_t</a>.</td></tr>
</table>
Example :<br />
<p class="code"><pre>
C++ : TCODImage *pix = TCODImage("mypix.bmp");
      // blitting the image without scaling it
      pix->blitRect(TCODConsole::root,40,25);
C   : TCOD_image_t pix = TCOD_image_new(10,10);
      /* down-scaling a 10x10 image to a 5x5 zone */
      TCOD_image_blit_rect(pix,NULL,40,25,5,5,TCOD_BKGND_SET);
Py  : pix = libtcod.image_new(10,10)
      # down-scaling a 10x10 image to a 5x5 zone
      libtcod.image_blit_rect(pix,0,40,25,5,5,libtcod.BKGND_SET)
</pre></p>

<h3>TCODImage::setKeyColor</h3>
When blitting an image, you can define a key color that will be ignored by the blitting function. This makes it possible to blit non rectangular images or images with transparent pixels.<br />
<p class="code"><pre>
C++ : void TCODImage::setKeyColor(const TCODColor keyColor)
C   : void TCOD_image_set_key_color(TCOD_image_t image, TCOD_color_t keyColor)
Py  : image_set_key_color(image, keyColor)
</pre></p>
<table class="param">
<tr><th>Parameter</th><th>Description</th></tr>
<tr><td>image</td><td>In the C and python version, the image handler, obtained with the <a href="image_load.html">load</a> function.</td></tr>
<tr><td>color</td><td>Pixels with this color will be skipped by blitting functions.</td></tr>
</table>
Example :<br />
<p class="code"><pre>
C++ : TCODImage *pix = TCODImage("mypix.bmp");
      // set pink as key color
      pix->setKeyColor(TCODColor(255,0,255));
      // blitting the image, omitting pink pixels
      pix->blitRect(TCODConsole::root,40,25);
C   : TCOD_image_t pix = TCOD_image_new(10,10);
      TCOD_image_set_key_color(pix,TCOD_red);
      TCOD_image_blit_rect(pix,NULL,40,25,5,5,TCOD_BKGND_SET);
Py  : pix = libtcod.image_new(10,10)
      libtcod.image_set_key_color(pix,libtcod.red)
      libtcod.image_blit_rect(pix,0,40,25,5,5,libtcod.BKGND_SET)
</pre></p>

<h3>TCODImage::blit2x</h3>
Eventually, you can use some special characters in the libtcod fonts :<br />
<img src="subcell.png"><br />
to double the console resolution using this blitting function.<br />
<p class="code"><pre>
C++ : void TCODImage::blit2x(TCODConsole *dest, int dx, int dy, int sx=0, int sy=0, int w=-1, int h=-1 ) const;
C   : void TCOD_image_blit_2x(TCOD_image_t image, TCOD_console_t dest, int dx, int dy, int sx, int sy, int w, int h);
Py  : image_blit_2x(image, dest, dx, dy, sx=0, sy=0, w=-1, h=-1)
</pre></p>
<table class="param">
<tr><th>Parameter</th><th>Description</th></tr>
<tr><td>image</td><td>In the C and python version, the image handler, obtained with the <a href="image_load.html">load</a> function.</td></tr>
<tr><td>dest</td><td>The console of which the image will be blited. Foreground, background and character data will be overwritten.</td></tr>
<tr><td>dx,dy</td><td>Coordinate of the console cell where the upper left corner of the blitted image will be.</td></tr>
<tr><td>x,y,w,h</td><td>Part of the image to blit. Use -1 in w and h to blit the whole image.</td></tr>
</table>
Example :<br />
<p class="code"><pre>
C++ : TCODImage *pix = TCODImage("mypix.bmp");
      // blitting the image with subcell resolution
      pix->blit2x(TCODConsole::root,10,5);
C   : TCOD_image_t pix = TCOD_image_new(10,10);
      TCOD_image_blit_2x(pix,NULL,10,5,0,0,-1,-1);
Py  : pix = libtcod.image_new(10,10)
      libtcod.image_blit_2x(pix,0,10,5)
</pre></p>
<table><tr><td>
Comparison before/after subcell resolution in TCOD :<br />
<img src="subcell_comp.png"></td><td>
Pyromancer ! screenshot, making full usage of subcell resolution :<br />
<img src="subcell_pyro.png"></td></tr></table>